<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Using the Golem library &mdash; Golem v1.0 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '',
          VERSION:     '1.0',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: ''
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/interface.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="contents" title="Global table of contents" href="contents.html" />
    <link rel="index" title="Global index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="top" title="Golem v1.0 documentation" href="index.html" />
    <link rel="next" title="Golem examples" href="examples.html" />
    <link rel="prev" title="CML/Golem dictionary syntax" href="dictionarysyntax.html" />
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="examples.html" title="Golem examples"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="dictionarysyntax.html" title="CML/Golem dictionary syntax"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Golem v1.0 documentation</a> &raquo;</li>
      </ul>
    </div>
    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  
  <div class="section" id="using-the-golem-library">
<h1 id="using-the-golem-library">Using the Golem library<a class="headerlink" href="#using-the-golem-library" title="Permalink to this headline">¶</a></h1>
<p>In this chapter, we move from considering the Golem markup language to the
Golem library. If you aren&#8217;t familiar with the Python programming language,
it&#8217;ll be helpful to have a look at the Python tutorial
(<a class="reference external" href="http://www.python.org/doc/tut">http://www.python.org/doc/tut</a>).</p>
<p>Any code samples starting with:</p>
<div class="highlight"><pre><span class="go">&gt;&gt;&gt;</span>
</pre></div>
<p>are example interactive sessions; you can start a Python interactive shell
by simply running <tt class="docutils literal"><span class="pre">python.</span></tt></p>
<div class="section" id="importing-golem-and-loading-a-dictionary">
<h2 id="importing-golem-and-loading-a-dictionary">Importing Golem and loading a dictionary<a class="headerlink" href="#importing-golem-and-loading-a-dictionary" title="Permalink to this headline">¶</a></h2>
<div class="section" id="if-you-have-installed-golem-using-setup-py-setuptools-easy-install">
<h3 id="if-you-have-installed-golem-using-setup-py-setuptools-easy-install">If you have installed Golem using setup.py/setuptools/<tt class="docutils literal"><span class="pre">easy_install</span></tt><a class="headerlink" href="#if-you-have-installed-golem-using-setup-py-setuptools-easy-install" title="Permalink to this headline">¶</a></h3>
<p>Golem will be on your PYTHONPATH, so you can simply use <tt class="docutils literal"><span class="pre">import</span> <span class="pre">golem</span></tt>
in your script.</p>
</div>
<div class="section" id="if-you-have-installed-golem-using-make-unix-macos-x-only">
<h3 id="if-you-have-installed-golem-using-make-unix-macos-x-only">If you have installed Golem using <tt class="docutils literal"><span class="pre">make</span></tt> (Unix/MacOS X only)<a class="headerlink" href="#if-you-have-installed-golem-using-make-unix-macos-x-only" title="Permalink to this headline">¶</a></h3>
<p>If you have installed Golem using <tt class="docutils literal"><span class="pre">make</span></tt>, you will need to set your
PYTHONPATH. Either set the PYTHONPATH environment variable:</p>
<div class="highlight"><pre><span class="nv">$ </span><span class="nb">export </span><span class="nv">PYTHONPATH</span><span class="o">=</span>/usr/local/share/pygolem:<span class="nv">$PYTHONPATH</span>
</pre></div>
<p>or pass it on the command line when you invoke <tt class="docutils literal"><span class="pre">python</span></tt>:</p>
<div class="highlight"><pre><span class="nv">$ PYTHONPATH</span><span class="o">=</span>/usr/local/share/pygolem:<span class="nv">$PYTHONPATH</span> python
</pre></div>
</div>
</div>
<div class="section" id="loading-a-dictionary-and-looking-up-terms">
<h2 id="loading-a-dictionary-and-looking-up-terms">Loading a dictionary and looking up terms<a class="headerlink" href="#loading-a-dictionary-and-looking-up-terms" title="Permalink to this headline">¶</a></h2>
<div class="section" id="loading-a-dictionary">
<h3 id="loading-a-dictionary">Loading a dictionary<a class="headerlink" href="#loading-a-dictionary" title="Permalink to this headline">¶</a></h3>
<p>Running Python interactively:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">golem</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">d</span> <span class="o">=</span> <span class="n">golem</span><span class="o">.</span><span class="n">Dictionary</span><span class="p">(</span><span class="s">&quot;/PATH/TO/DICTIONARY&quot;</span><span class="p">)</span>
</pre></div>
<p><tt class="docutils literal"><span class="pre">d</span></tt> is now an instance of <tt class="docutils literal"><span class="pre">golem.Dictionary</span></tt>, which inherits from (the
Python type) <tt class="docutils literal"><span class="pre">dict</span></tt>. Thus, <tt class="docutils literal"><span class="pre">d.keys()</span></tt>, for instance, will list all the
terms in the dictionary.</p>
</div>
<div class="section" id="looking-up-terms">
<h3 id="looking-up-terms">Looking up terms<a class="headerlink" href="#looking-up-terms" title="Permalink to this headline">¶</a></h3>
<p>Terms in the dictionary are indexed by keys in <em>Clark form</em>:
<tt class="docutils literal"><span class="pre">{namespace}id</span></tt>, where <tt class="docutils literal"><span class="pre">namespace</span></tt> is the dictionary&#8217;s namespace URI and
<tt class="docutils literal"><span class="pre">id</span></tt> is the ID of the dictionary entry you&#8217;re looking up. Thus, an entry
<tt class="docutils literal"><span class="pre">cutoff</span></tt> in a dictionary with
namespace <tt class="docutils literal"><span class="pre">http://www.castep.org/cml/dictionary/</span></tt>:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cutoff</span> <span class="o">=</span> <span class="n">d</span><span class="p">[</span><span class="s">&quot;{http://www.castep.org/cml/dictionary/}cutoff&quot;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">cutoff</span>
<span class="go">&lt;golem.Entry object at 0x20172d0&gt;</span>
</pre></div>
<p>If there was no <tt class="docutils literal"><span class="pre">cutoff</span></tt> entry in this dictionary, a <tt class="docutils literal"><span class="pre">KeyError</span></tt> exception
would be raised. We can then use this to find instances of this concept in a
CML file:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cutoffs</span> <span class="o">=</span> <span class="n">cutoff</span><span class="o">.</span><span class="n">findin</span><span class="p">(</span><span class="s">&quot;LiH-geomopt1.cml&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">cutoffs</span>
<span class="go">[&lt;golem.EntryInstance object at 0x202ced0&gt;]</span>
</pre></div>
<p><tt class="docutils literal"><span class="pre">findin</span></tt> always returns a list - if the concept is present, it returns all
the instances of the concept (or its implementations or synonyms) in document
order, and an empty list if the concept is not found. One can then extract the
value of these instances, as follows:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">val</span> <span class="o">=</span> <span class="n">cutoffs</span><span class="p">[</span><span class="mf">0</span><span class="p">]</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">val</span>
<span class="go">330.0</span>
</pre></div>
<p>and once you&#8217;ve obtained a value, check what its units are, and which term
it is an example of:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">val</span><span class="o">.</span><span class="n">entry</span>
<span class="go">&lt;golem.Entry object at 0x20172d0&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">val</span><span class="o">.</span><span class="n">unit</span>
<span class="go">u&#39;castepunits:eV&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">val</span><span class="o">.</span><span class="n">entry</span><span class="o">.</span><span class="n">term</span>
<span class="go">&#39;Basis set cutoff energy&#39;</span>
</pre></div>
<p>In the next section, we show some examples of how to use Golem for real-world
data-extraction from CML files, taken from the reporting component of
<a class="reference external" href="http://www.materialsgrid.org/">MaterialsGrid</a>.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3>Table Of Contents</h3>
            <ul>
<li><a class="reference external" href="">Using the Golem library</a><ul>
<li><a class="reference external" href="#importing-golem-and-loading-a-dictionary">Importing Golem and loading a dictionary</a><ul>
<li><a class="reference external" href="#if-you-have-installed-golem-using-setup-py-setuptools-easy-install">If you have installed Golem using setup.py/setuptools/<tt class="docutils literal"><span class="pre">easy_install</span></tt></a></li>
<li><a class="reference external" href="#if-you-have-installed-golem-using-make-unix-macos-x-only">If you have installed Golem using <tt class="docutils literal"><span class="pre">make</span></tt> (Unix/MacOS X only)</a></li>
</ul>
</li>
<li><a class="reference external" href="#loading-a-dictionary-and-looking-up-terms">Loading a dictionary and looking up terms</a><ul>
<li><a class="reference external" href="#loading-a-dictionary">Loading a dictionary</a></li>
<li><a class="reference external" href="#looking-up-terms">Looking up terms</a></li>
</ul>
</li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="dictionarysyntax.html" title="previous chapter">CML/Golem dictionary syntax</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="examples.html" title="next chapter">Golem examples</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/usinglibrary.txt">Show Source</a></li>
            </ul>
            <h3>Quick search</h3>
            <form class="search" action="search.html" method="get">
              <input type="text" name="q" size="18" /> <input type="submit" value="Go" />
              <input type="hidden" name="check_keywords" value="yes" />
              <input type="hidden" name="area" value="default" />
            </form>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="examples.html" title="Golem examples"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="dictionarysyntax.html" title="CML/Golem dictionary syntax"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Golem v1.0 documentation</a> &raquo;</li>
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2008, Andrew Walkingshaw.
      Last updated on Oct 01, 2008.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
    </div>
  </body>
</html>